.TH PROTOCOLS.CFG 5 "Version 4.3.13:  7 Jan 2014" "Xymon"
.SH NAME
protocols.cfg \- Configuration of TCP network services

.SH SYNOPSIS
.BR $XYMONHOME/etc/protocols.cfg

.SH DESCRIPTION
\fBprotocols.cfg\fR contains definitions of how 
.I xymonnet(1)
should test a TCP-based network service (i.e. all common
network services except HTTP and DNS).
For each service, a simple dialogue can be defined to
check that the service is functioning normally, and optional
flags determine if the service has e.g. a banner or requires
SSL- or telnet-style handshaking to be tested.

.SH FILE FORMAT
protocols.cfg is a text file. A simple service definition for
the SMTP service would be this:
.br
.sp
   [smtp]
.br
      send "mail\\r\\nquit\\r\\n"
.br
      expect "220"
.br
      options banner
.br
.sp
This defines a service called "smtp". When the connection is
first established, xymonnet will send the string "mail\\r\\nquit\\r\\n"
to the service. It will then expect a response beginning with "220".
Any data returned by the service (a so-called "banner") will be recorded 
and included in the status message.
.sp
The full set of commands available for the protocols.cfg file are:

.IP "[NAME]"
Define the name of the TCP service, which will also be the column-name
in the resulting display on the test status. If multiple tests share 
a common definition (e.g. ssh, ssh1 and ssh2 are tested identically),
you may list these in a single "[ssh|ssh1|ssh2]" definition,
separating each service-name with a pipe-sign.

.IP "send STRING"
.IP "expect STRING"
Defines the strings to send to the service after a connection is
established, and the response that is expected. Either of these
may be omitted, in which case
.I xymonnet(1)
will simply not send any data, or match a response against anything.

The send- and expect-strings use standard escaping for non-printable
characters. "\\r" represents a carriage-return (ASCII 13), "\\n"
represents a line-feed (ASCII 10), "\\t" represents a TAB (ASCII 8). 
Binary data is input as "\\xNN" with NN being the hexadecimal value
of the byte.

.IP "port NUMBER"
Define the default TCP port-number for this service. If no portnumber
is defined,
.I xymonnet(1)
will attempt to lookup the portnumber in the standard /etc/services 
file.

.IP "options option1[,option2][,option3]"
Defines test options. The possible options are
.br
   banner - include received data in the status message
.br
   ssl - service uses SSL so perform an SSL handshake
.br
   telnet - service is telnet, so exchange telnet options


.SH FILES
.BR $XYMONHOME/etc/protocols.cfg

.SH "SEE ALSO"
xymonnet(1)

